ATOM Documentation

← Back to App

Deploy to AWS App Runner (with Upstash & Neon)

This guide explains how to deploy the Atom SaaS hybrid container (Next.js + Python) to AWS App Runner.

Architecture

  • **Compute**: AWS App Runner (serverless container runner).
  • **Database**: Neon (Postgres) or AWS RDS.
  • **Cache/Rate Limits**: Upstash Redis (or AWS ElastiCache).
  • **Container**: Single hybrid image exposing port 3000 (Next.js) which proxies API calls to localhost:8000 (Python).

---

1. Prerequisites

  • AWS CLI installed and configured (aws configure).
  • Docker installed.
  • An existing ECR repository (or create one):

---

2. Build & Push Image

  1. **Authenticate Docker with ECR**:
  1. **Build the Image**:
  1. **Tag & Push**:

---

3. Configure Upstash Redis

Since App Runner instances are ephemeral and effectively serverless, **Upstash Redis** is the recommended serverless Redis solution if you want to avoid managing VPCs for ElastiCache.

  1. Create a database in the Upstash Console.
  2. Copy the **UPSTASH_REDIS_REST_URL** and **UPSTASH_REDIS_REST_TOKEN**.
  3. **IMPORTANT**: For Rate Limiting (abuse-protection.ts), we use the standard Redis client (redis npm package), so you need the **TCP connection string**, typically rediss://default:[password]@[endpoint]:[port].

---

4. Create App Runner Service

  1. Go to **AWS App Runner Console** > **Create service**.
  2. **Source**: Container registry > Amazon ECR.
  3. **Image URI**: Select the image you pushed (atom-saas:latest).
  4. **Deployment settings**: "Automatic" (redeploys on new push) or "Manual".

Configuration

  • **Runtime**:
  • **Port**: 3000 (This is critical. Next.js runs on 3000).
  • **Environment variables**:
VariableValueDescription
NODE_ENVproductionOptimization
DATABASE_URLpostgresql://...Connection to Neon or RDS
REDIS_URLrediss://...Upstash TCP connection string
NEXTAUTH_SECRET[random-string]For NextAuth.js
NEXTAUTH_URLhttps://[your-app-runner-url].awsapprunner.comUpdate after creation
JWT_SECRET[random-string]For API auth
PYTHON_BACKEND_URLhttp://localhost:8000**Default**, but explicit is safe
  • **Resources**:
  • **CPU**: 1 vCPU (minimum).
  • **Memory**: 2 GB (Recommended for hybrid stack).

---

5. Security & VPC (Optional)

If you decide to use **AWS RDS** and **ElastiCache** instead of Neon/Upstash:

  1. Create a **VPC Connector** in App Runner settings.
  2. Select the Subnets/Security Groups that have access to your RDS/ElastiCache instances.

---

6. Verify Deployment

  1. Wait for the service status to become **Running**.
  2. Visit the App Runner default domain.
  3. Test a Python API route (e.g. GET /api/backend/health -> proxies to http://localhost:8000/api/health).

---

Troubleshooting

  • **502 Bad Gateway**: App Runner health check failed. Ensure the container exposes port 3000 and starts within the timeout.
  • **Python errors**: Check Application Logs in console. If uvicorn fails to start, the entrypoint.sh trap will kill the container.